hal-browser

HAL browser

This package provides a middleware for HAL APIs.

The middleware looks for HAL and JSON responses, and automatically converts them into a HTML interface if a browser access them.

It does so via the Accept: text/html header. If this header is not provided, the middleware does nothing.

It automatically decorates the following formats:

• application/json
• application/problem+json
• application/hal+json
• text/markdown

Screenshot

An example. If a API normally returns the following HAL format:

{
  "_links": {
    "self": { "href": "/testing" },
    "previous": {
      "href": "/testing/?page=1",
      "title": "Previous page"
    },
    "next": {
      "href": "/testing/?page=2",
      "title": "Next page"
    },
    "author": {
      "href": "https://evertpot.com",
      "title": "Evert Pot"
    },
    "help": {
      "href": "https://google.com/",
      "title": "Google it"
    },
    "search": {
      "href": "https://google.com/{?q}",
      "templated": true
    },
    "edit": { "href": "/testing" },
    "create-form": { "href": "/testing" },
    "my-link": {
      "href": "/foo-bar",
      "title": "Custom link"
    },
    "alternate": [
      {
        "href": "/testing/markdown",
        "type": "text/markdown",
        "title": "Markdown test"
      },
      {
        "href": "/testing/csv",
        "type": "text/csv",
        "title": "Csv test"
      },
      {
        "href": "/testing/rss",
        "type": "application/rss+xml",
        "title": "RSS"
      },
      {
        "href": "/testing/rss",
        "type": "application/atom+xml",
        "title": "Atom"
      }
    ],
    "code-repository": { "href": "https://github.com/evert/hal-browser" },
    "redirect-test": { "href": "/redirect-test" }
  },
  "msg": "Hello world!",
  "version": "0.5.0",
  "name": "test resource!"
}

The browser will automatically convert it to this HTML format:

This screenshot is an example of the browser automatically formatting a .csv and parsing HTTP Link headers:

The following example converts this:

{
  "_links": {
    "self": {
      "href": "/testing/form"
    },
    "up": {
      "href": "/testing",
      "title": "Back to testing home"
    },
    "my-form": {
      "href": "/testing/form{?startDate}{?endDate}",
      "title": "Search by date range",
      "templated": true
    }
  }
}

And automatically turns the templated link into a form:

Supported frameworks

• Curveball - DONE
• Express - DONE
• Koa - TODO

Installation

npm install hal-browser

Getting started

Curveball

import { Application } from 'curveball/@core';
import halBrowser from 'hal-browser';

const app = new Application();
app.use(halBrowser({});

Express

Express support is handled via a special express middleware. Check out the hal-browser-express package.

Koa

TODO

Options

The halBrowser function takes an options object, which can take the following settings:

• title - Change the main title.
• stylesheets - Provide your own stylesheets. This is an array of strings. these are relative urls, and they are automatically expanded based on the assetBaseUrl setting.
• navigationLinks - Specify (or remove) links that show up in the top navigation.
• serveAssets - by default the browser plugin will also take responsibility for serving icons and stylesheet. If you're hosting these assets elsewhere, set this to false.
• defaultLinks - A list of links that will show up by default, whether or not they were specified by the API. By default a home link is added here.
• hiddenRels - List of relationship types that will be hidden from the user by default. This can be used for links that are simply not interesting for a human to see. (default: ['self', 'curies'].

Example:

app.use(halBrowser({
  title: 'My API',
  stylesheets: [
    '/my-stylesheet.css',
  ],

  // This should end with a / generally.
  assetBaseUrl: 'http://some-cdn.example.org/',

  navigationLinks: {
    // Create new 'author' button
    'author' : {
      // optional css class, by default this will be `rel-author`
      cssClass: 'rel-blabla',

      // Optional title to show when hovering over button
      defaultTitle: 'Click me',

      // Override icon. Also optional
      icon: 'icons/foobar.svg',

      // Either 'header' (default) or 'pager'
      position: 'header'

      // Set the order. Lower is earlier. Default is 0.
      priority: -100,

    },
    // passing 'true' will use default setting for the button
    'help' : true,

    // passing 'null' will remove the icon, if it was a default icon
    'up': null,
  },

  defaultLinks: [
    // Every page will have a 'help' link
    {
      rel: 'help',
      href: 'https://example.org/help',
      title: 'Support',
    }
  ],
});

Future features

• Add a link to allow the user to see the raw format.
• Show metadata, such as Last-Modified